Publishing a Custom Go GitHub Action
Understand the procedure to publish our custom Go GitHub Action.
The superpower of GitHub Actions is the community and the actions that the community publishes to the GitHub Marketplace. Think about how much more work we would have had to do in the previous sections if we didn’t have community actions available for use. Our workflows would have had to start from first principles, involving authoring long, tedious scripts to complete tasks that we were able to express in a handful of YAML instead.
Open source software is not only about having access to free software but also about giving back to the community. We are going to learn how to give back to the GitHub Actions community through publishing an action to GitHub Marketplace. This will enable the entire user community of GitHub to benefit from it.
In this lesson, we will learn how to publish a custom action to the GitHub Marketplace. We will learn the basics of publishing actions. After covering the basics, we will learn how to automate versioning for a published action. We will learn how to use the tweeter action to tweet an announcement of new releases to tweeter. Finally, we will learn how to publish our action to the GitHub Marketplace so that it can be used by the rest of the GitHub community across the world.
The basics of publishing actions#
Publishing an action to the GitHub Marketplace adds some requirements and best practices that, for a local action, as we built in the previous section, do not apply. For example, the readme for the repository will be the landing page for the action in the marketplace, so we'd want to provide a description and usage guidance for the repository readme.
The following are the requirements for publishing an action to the GitHub Marketplace:
The action must be in a public GitHub repository.
In the root of the repository must be a single action named
action.yamloraction.yml.The name of the action in
action.yamlmust be unique to the marketplace. The name may not overlap with any GitHub features or products, or any other names that GitHub reserves.A public action should follow
v1andv1.2.3semantic version guidance so that users of the action can specify a full semantic version, or simplyv1to denote the latest in thev1major semantic version series.
Goals for publishing the tweeter custom action#
The following are goals for publishing the tweeter custom action:
Set up a release-triggered workflow that will handle semantic version management.
Publish the tweeter action to the GitHub Marketplace.
Managing action semantic versioning#
The first and second goals of publishing the tweeter custom action to the marketplace are as follows:
Set up a release-triggered workflow that will handle semantic version management.
Use the action to tweet an announcement of the new release of the action.
We are going to build a workflow to update the major version tag—for example, v1—to point to the latest release in the v1.x.x series of semantic versions. The workflow will also be responsible for creating new major version tags as new major semantic versions are released:
The preceding workflow does the following:
Triggers on a release being published or on a manual UI submission. This means that a project maintainer can trigger the workflow via the GitHub UI if ad hoc execution is required.
Declares that the workflow requires rights to write to the repository. This is used to write tags.
Declares the
TAG_NAMEenvironment variable, which is either the ad hoc job input or the tag of the release.The
update_tagtakes the tag inv1.2.3format and updates the tag's major semantic version tag to the latest version within that major semantic version. For example, if the new release tag isv1.2.3, then thev1tag will point to the same Git ref asv1.2.3.Clones the source code using
actions/checkout@v2.Tweets about the new release using Twitter developer credentials embedded in GitHub repository secrets. To set up Twitter developer credentials, go to the Twitter developer portal and set up an account and application. After we gather the secrets, we can add them to the repository secrets under the “Settings” tab, as shown in the following screenshot:
With the preceding workflow, when we apply a tag – for example, v1.2.3 – the repository will also be tagged at the same Git ref with v1. After the tags are set, the tweeter action will execute, announcing the release to the world.
Recall from the previous section that when we tag the tweeter repository with a semantic version, the release workflow will trigger, causing a new release to be created. This workflow will then trigger the action version update release workflow, which will tag the action with the major version and announce through Twitter that the action release is available.
All that is left to do is to release the action to the GitHub Marketplace. This only needs to be done the first time the action is released.
Publishing the tweeter action to the GitHub Marketplace#
The final goal of publishing the tweeter custom action is to publish the tweeter action to the GitHub Marketplace. The first publication of our GitHub Action is a manual process and can be accomplished by following this guide on GitHub. After taking this first set of manual steps, they will not need to be repeated for future releases.
Creating a Custom GitHub Action Using Go
Summary and Quiz on Automating Workflows With GitHub Actions